Release 10.1A: OpenEdge Development:
Progress 4GL Handbook

Using BUFFER-FIELD objects

As you saw in the previous chapter, there is a BUFFER-FIELD object for each field in a buffer, whether the buffer is static or dynamic. You can access a field within a buffer through its handle, using one of two types of arguments to the BUFFER-FIELD method, either its ordinal position within the buffer or its fieldname.

Buffer fields have all the same attributes that static field-level objects have. You’re already familiar with these attributes from static syntax, including COLUMN-LABEL, DATA-TYPE, DBNAME, DECIMALS, EXTENT, FORMAT, HANDLE, HELP, INITIAL, LABEL, MANDATORY, NAME, TABLE, and WIDTH-CHARS. Buffer field objects also have several useful attributes distinctive to the object and accessible only through its handle. This section summarizes those objects.

You cannot create or delete a buffer field independent of its buffer. Buffer field objects are created when a buffer is created. They are deleted along with the buffer, if it is dynamic. In the case of static buffers, the buffer field is really just a handle through which you can access useful attributes.

BUFFER-HANDLE attribute

This attribute is the handle of the buffer the field belongs to. So, the BUFFER-FIELD handle points from the buffer to one of its fields, and the BUFFER-HANDLE points from any field back to its buffer.

BUFFER-NAME attribute

This CHARACTER attribute holds the name of the buffer the field belongs to.

BUFFER-VALUE and STRING-VALUE attributes

The BUFFER-VALUE is the value of the field in its native data type. The attribute therefore holds a value in whatever the data type of the field is. The STRING-VALUE, on the other hand, is a CHARACTER attribute that holds the field value as it is formatted for display. It is therefore in the same format as the SCREEN-VALUE of a displayed field. Note that this is not necessarily the same as what the expression STRING(hField:BUFFER-VALUE) would return, because the STRING-VALUE includes any characters that are part of the field format, whereas using the STRING function simply turns the value into a character string without applying any special formatting to it.

POSITION attribute

This INTEGER attribute is the ordinal position of the field within the buffer.

Note that there is a difference between the order of the fields you obtain using the BUFFER-FIELD(n) form to identify the field and the value of the field’s POSITION attribute. The order using BUFFER-FIELD(n) is the display order of the fields, which is determined using the Order # as it is assigned in the Data Dictionary. The POSITION attribute is assigned internally as fields are created for a table, and does not change, even though the display Order # can be changed. In addition, the first field position is reserved so that the numbering of the POSITION begins with 2. For example, this code shows the POSITION attribute value for each Customer field:

DEFINE VARIABLE hCust  AS HANDLE  NO-UNDO. DEFINE VARIABLE hField AS HANDLE  NO-UNDO. DEFINE VARIABLE cLabel AS CHARACTER FORMAT "X(20)" NO-UNDO. DEFINE VARIABLE cValue AS CHARACTER FORMAT "X(40)" NO-UNDO. DEFINE VARIABLE iCount AS INTEGER NO-UNDO. hCust = BUFFER Customer:HANDLE. hCust:FIND-FIRST("WHERE CustNum = 1", NO-LOCK). REPEAT iCount = 1 TO hCust:NUM-FIELDS:      ASSIGN hField = hCust:BUFFER-FIELD(iCount)             cLabel = hField:LABEL             cValue = hField:STRING-VALUE.   DISPLAY cLabel hField:POSITION FORMAT "Z9" LABEL "Position" cValue. END.

Figure 19–10 shows the result.

Figure 19–10: Result of using the POSITION attribute

The following chapter continues the discussion of dynamic data management objects with information on how to create and use dynamic temp-tables and dynamic browses.